SYSTEM$SEND_EMAIL と SYSTEM$SEND_SNOWFLAKE_NOTIFICATION の違いを整理してみる #SnowflakeDB

モダンデータスタック(MDS)

#Snowflake

安原朋紀

2024.08.19

はじめに

Snowflake ではEメールによる通知を送信するためのストアドプロシージャとしてSYSTEM$SEND_EMAIL を使用できます。また、2024年5月のリリースで SYSTEM$SEND_SNOWFLAKE_NOTIFICATION が使用できるようになりました。こちらの機能でも Eメールの送信が可能なため、どのような違いがあるのか、それぞれの概要と合わせて整理しておきたく記事としました。

まとめ

それぞれの主な違いは以下の通りです。

内容	SYSTEM$SEND_EMAIL	SYSTEM$SEND_SNOWFLAKE_NOTIFICATION
指定できる通知統合のタイプ	EMAILのみ	EMAIL以外も指定可能
指定できる通知統合	1回の呼び出しで1種類のみ	1回の呼び出しで複数指定可能
メッセージのタイプ	text/plain , text/html	text/plain , text/html, application/json

上記の他、SYSTEM$SEND_SNOWFLAKE_NOTIFICATION では以下の特徴があります。

関数に渡す JSON 形式の文字列を生成するためのヘルパー関数の使用が可能
EMAIL 通知統合のデフォルト値の上書きが可能

それぞれの特徴とあわせて以降で詳しく見ていきます。

SYSTEM$SEND_EMAIL

SYSTEM$SEND_EMAIL は、同じ Snowflake アカウントのユーザーに対して電子メール通知を送信できるストアドプロシージャです。前提条件として送信先のメールアドレスは、各ユーザーのプロファイルで登録・認証済みのメールアドレスである必要があります。
メール通知送信までの一連の手順は以下にまとまっているので。こちらに沿って確認してみます。

メールアドレスの確認

メールを受信するユーザーは、メールアドレスの確認が必要です。Snowsigh からの場合は、以下に記載の手順で実施できます。

EMAIL 通知統合の作成

メールによる通知統合の作成は以下に記載があります。

こちらはドキュメント記載の例ですが、TYPEオプションの値としてEMAILを指定することで、EMAIL 通知統合として作成できます。

CREATE NOTIFICATION INTEGRATION my_email_int
  TYPE=EMAIL
  ENABLED=TRUE
  ALLOWED_RECIPIENTS=('first.last@example.com','first2.last2@example.com');

また、オプションのALLOWED_RECIPIENTS を指定することで、その統合オブジェクトで通知の送信先に指定できるメールアドレスを限定することが可能です。

メール通知の送信

メール通知の送信にSYSTEM$SEND_EMAILを使用します。関数の構文は以下のようになっており<integration_name>として EMAIL 通知統合を指定します。

SYSTEM$SEND_EMAIL(
  '<integration_name>',
  '<email_address_1> [ , ... <email_address_N> ]',
  '<email_subject>',
  '<email_content>',
  [ '<mime_type>' ] )

SYSTEM$SEND_EMAIL | Snowflake Documentation

以下はドキュメント記載の例ですがこちらを実行してみます。

--EMAIL通知統合の作成
CREATE OR REPLACE NOTIFICATION INTEGRATION my_email_int
  TYPE=EMAIL
  ENABLED=TRUE;

--ストアドプロシージャを実行してメールを送信
CALL SYSTEM$SEND_EMAIL(
    'my_email_int',
    '<確認済みのメールアドレス>',
    'Email Alert: Task A has finished.',
    'Task A has successfully finished.\nStart Time: 10:10:32\nEnd Time: 12:15:45\nTotal Records Processed: 115678'
);

注意点として、通知統合作成時にALLOWED_RECIPIENTSを指定し、ストアドプロシージャ実行時に確認済みのメールアドレスとして、ここで指定した以外のメールアドレスで実行した場合や、そもそもアカウントで認証されていないメールアドレスを指定しストアドプロシージャを実行した場合は下図のようにエラーとなります。

問題なく実行されると下図のようなメールが届きます。

HTML 形式も使用できるので、その場合はさいごのオプションでtext/htmlを指定します。※デフォルトはtext/plain

CALL SYSTEM$SEND_EMAIL(
    'my_email_int',
    '<メールアドレス>',
    'Email Alert: Task A has finished.',
    '<html>
        <body>
            <h2 style="color: #2e6c80;">Email Alert: Task A has finished</h2>
            <p>Task A has successfully finished.</p>
            <table border="1" cellpadding="5" cellspacing="0">
                <tr>
                    <th>Start Time</th>
                    <td>10:10:32</td>
                </tr>
                <tr>
                    <th>End Time</th>
                    <td>12:15:45</td>
                </tr>
                <tr>
                    <th>Total Records Processed</th>
                    <td>115,678</td>
                </tr>
            </table>
        </body>
    </html>',
    'text/html'
);

届いたメールの内容

SYSTEM$SEND_SNOWFLAKE_NOTIFICATION

通知統合はメッセージのタイプごとにTYPEに異なる値を指定します（EMAIL ,QUEUE ,WEBHOOK）。SYSTEM$SEND_SNOWFLAKE_NOTIFICATIONでも通知統合を指定しますが、この際通知統合のタイプとしてEMAIL以外も選択できる点が大きな特徴です。

その他には以下のような特徴があります。

1回の呼び出しで複数の通知統合を指定できる
- このため、異なるメッセージタイプであっても1回の呼び出しで処理を実行できます
EMAIL 通知統合のデフォルト値の上書きが可能
メッセージタイプとしてapplication/json を指定可能

通知の送信

はじめに、このストアドプロシージャでの通知の送信について見てみます。以下は EMAIL 通知統合を指定する公式ドキュメントの例を引用したものですが、送信するメッセージと使用する通知統合やその設定を JSON 形式の文字列として渡します。

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
   -- Message type and content.
  '{ "text/html": "<p>This is a message.</p>" }',
  -- Integration used to send the notification and values used for the subject and recipients.
  -- These values override the defaults specified in the integration.
  '{
    "my_email_int": {
      "subject": "Status update",
      "toAddress": ["person_a@example.com", "person_b@example.com"],
      "ccAddress": ["person_c@example.com"],
      "bccAddress": ["person_d@example.com"]
    }
  }'
);

JSON 形式での指定なので Notification functions としてJSON 形式の文字列を構築するヘルパー関数をストアドプロシージャ内で指定することができます。

上記のクエリをヘルパー関数で構築すると以下のようになります。

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
  SNOWFLAKE.NOTIFICATION.TEXT_HTML('<p>a message</p>'),
  SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG(
    'my_email_int',
    'Status update',
    ARRAY_CONSTRUCT('person_a@example.com', 'person_b@example.com'),
    ARRAY_CONSTRUCT('person_c@example.com'),
    ARRAY_CONSTRUCT('person_d@example.com')
  )
);

複数の通知統合を指定

複数の統合を使用するには、ARRAY_CONSTRUCT 関数を呼び出し指定したい統合の配列を構築し、その配列をストアドプロシージャの2番目の引数として与えます。

例として以下では、メッセージの通知先として３つの統合オブジェクトを指定しています。my_sns_intでは Amazon SNS に対してEMAIL をエンドポイントとして、my_slack_webhook_intでは Slack に対する通知統合を作成しています。

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
  '{"text/plain":"Specify multiple notification integrations"}',
  ARRAY_CONSTRUCT(
    SNOWFLAKE.NOTIFICATION.INTEGRATION('my_sns_int'),
    SNOWFLAKE.NOTIFICATION.INTEGRATION('my_slack_webhook_int'),
    SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG('my_email_int','Mail title',ARRAY_CONSTRUCT('<メールアドレス>'))
  )
);

また、メッセージを送信するために使用する通知統合を指定する JSON オブジェクトを返すためにヘルパー関数である SNOWFLAKE.NOTIFICATION.INTEGRATION 関数を使用しています。メール通知の設定については、各オプションを指定できる SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG を使用できます。

実行すると下図のようにメッセージを受信できます。※何度か通知を送信しています。

メール通知

Slack

EMAIL 通知統合のデフォルト値を上書き

EMAIL 通知統合を定義する際、以下のようにその通知統合を使用する場合のデフォルトの件名などを指定できます。

CREATE OR REPLACE NOTIFICATION INTEGRATION my_email_int
  TYPE=EMAIL
  ENABLED=TRUE
  ALLOWED_RECIPIENTS=('<メールアドレス>')
  DEFAULT_SUBJECT = 'Service status';

こちらの通知統合を使用しつつ、以下の内容で通知を送信してみます。EMAIL_INTEGRATION_CONFIGの２つ目の引数が件名を表しますが、NULL を渡すことで除外できます。

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
  SNOWFLAKE.NOTIFICATION.TEXT_PLAIN('A message'),
  SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG('my_email_int',NULL, ARRAY_CONSTRUCT('<メールアドレス>'))
  );

この場合、下図のようなデフォルトの件名でメールが届きます。

同じ通知統合で、今度は件名を指定してストアドプロシージャを実行します。

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
  SNOWFLAKE.NOTIFICATION.TEXT_PLAIN('A message'),
  SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG('my_email_int','件名を上書き', ARRAY_CONSTRUCT('メールアドレス'))
  );

下図の通り、通知統合の設定が上書きされたメールが届きます。

メッセージタイプとして`application/json`を指定

SYSTEM$SEND_SNOWFLAKE_NOTIFICATIONではメッセージのタイプとしてapplication/jsonを指定できます。この場合も、メッセージの内容は JSON 形式で渡すことになるのでヘルパー関数を使用できます。

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
  SNOWFLAKE.NOTIFICATION.APPLICATION_JSON('{ "name": "value" }'),
  SNOWFLAKE.NOTIFICATION.INTEGRATION('my_sns_int')
);

また、メッセージのタイプ毎に以下の関数を使用可能です。

HTML メールのメッセージを送信：TEXT_HTML
プレーンテキストのメッセージを送信TEXT_PLAIN
JSON メッセージを送信：APPLICATION_JSON

通知の内容

さいごに

SYSTEM$SEND_EMAILとSYSTEM$SEND_SNOWFLAKE_NOTIFICATIONそれぞれについてまとめてみました。前者はメール通知のためのシンプルな使い方が可能で、後者はメール以外の通知が必要な場合やまとめて複数の通知統合を使用する際に便利です。それぞれ適する場面で使い分けできればと思いました。
こちらの内容が何かの参考になれば幸いです。